Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix accessibility issues #1673

Merged
merged 6 commits into from
Oct 14, 2021
Merged

Fix accessibility issues #1673

merged 6 commits into from
Oct 14, 2021

Conversation

pfitzseb
Copy link
Member

@pfitzseb pfitzseb commented Aug 13, 2021 •
edited
Loading

The goal of this is to make sure Documenter-generated docs conform to WCAG 2.0.
I'm opening this early so I can document the changes as I work my way through them, which should hopefully make review a bit easier.

Color contrast

Light theme Version contrast

From: Contrast ratio 3.93
image
To: Contrast ratio 5.26
image

Dark theme code contrast

From: Contrast ratio 3.55
image
To: Contrast ratio 11.49
image

Elements

Nested lists in content

Currently, nested lists are rendered as

<ul>
    <li><a href="lib/public/#Public-Documentation">Public Documentation</a></li>
    <ul>
        <li><a href="lib/public/#Contents">Contents</a></li>
        <li><a href="lib/public/#Index">Index</a></li>
        <li><a href="lib/public/#Public-Interface">Public Interface</a></li>
        <li><a href="lib/public/#DocumenterTools">DocumenterTools</a></li>
    </ul>
</ul>

Having a ul as the direct child of another ul is invalid, so 01fb501 changes that to

<ul>
    <li><a href="lib/public/#Public-Documentation">Public Documentation</a></li>
    <li class="no-marker">
        <ul>
            <li><a href="lib/public/#Contents">Contents</a></li>
            <li><a href="lib/public/#Index">Index</a></li>
            <li><a href="lib/public/#Public-Interface">Public Interface</a></li>
            <li><a href="lib/public/#DocumenterTools">DocumenterTools</a></li>
        </ul>
    </li>
</ul>

without any difference in presentation.

Focus handling

Source link

The source link is not shown when tabbing through the page content. This PR will show the button at full opacity when it's focused
image
and at 0.2 opacity when something in the .docstring container is focused:
image

@pfitzseb pfitzseb changed the title WIP: Fix accesibility issues WIP: Fix accessibility issues Aug 13, 2021
@kimikage
Copy link
Contributor

This is off-topic, but for consistency, I think it would be better to remove the dependency on the "darkly" theme, which also changes the font size of menus and admonitions.
I haven't checked the impact on plugins, but removing the darkly is not so hard.

@mortenpi
Copy link
Member

Sorry for getting around to this earlier, but these changes all LGTM. Thanks @pfitzseb!

I'd be happy to merge this in it's current form if you don't have additional fixes right now, since I think it's already an improvement.

This is off-topic, but for consistency, I think it would be better to remove the dependency on the "darkly" theme, which also changes the font size of menus and admonitions. I haven't checked the impact on plugins, but removing the darkly is not so hard.

Darkly (kinda) is the current dark theme.. so it would have to be replaced with something. So when you say "remove", do you mean reducing the current dark theme down to something that would just override the colors basically? If yes, then I would support that completely --- just dropping Darkly in was kind of a shortcut to get a working dark theme in quickly, but it's definitely not ideal.

@pfitzseb pfitzseb marked this pull request as ready for review August 30, 2021 07:24
@pfitzseb
Copy link
Member Author

Yeah, I don't have any immediate plans to work on this further. There are some issues related to duplicate header ids, but I haven't yet have time to look into those.

@pfitzseb pfitzseb changed the title WIP: Fix accessibility issues Fix accessibility issues Sep 7, 2021
@sairus7
Copy link

sairus7 commented Sep 10, 2021 •
edited
Loading

I just paste here messages from Slack. Please open images in new pane to see them in original ratio:

I can't get rid of the feeling that dark documenter theme is harder to read than light one. Font looks thicker and red code lines look too dark:
image

And for comparison of dark themes - from top to bottom:

  1. Julia docs
  2. Slack text
  3. GitHub markdown

Looks like julia docs have more contrast, and bold text is blurry

image

@fredrikekre
Copy link
Member

Good to go? Perhaps worth adding a note in the changelog?

@pfitzseb
Copy link
Member Author

Yup, good to go.

@fredrikekre fredrikekre merged commit 08ecbb6 into master Oct 14, 2021
@fredrikekre fredrikekre deleted the sp/accessibility branch October 14, 2021 09:36
@mortenpi mortenpi added Format: HTML Related to the default HTML output Type: Enhancement labels Mar 23, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@mortenpi mortenpi Awaiting requested review from mortenpi

Assignees
No one assigned
Labels
Format: HTML Related to the default HTML output Type: Enhancement
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@pfitzseb @kimikage @mortenpi @sairus7 @fredrikekre